Summary

Using a pre-processor allows us to define value overwrites on a token using the $extensions['org.primer.overrides'] property.

Schema

type themeString = "light" | "dark" | "dark-high-contrast" // | ...
type overrideObject = {
  $value?: DesignTokenValue
  $alpha?: number
}
  
{
  $extensions: {
    'org.primer.overrides': 
      {
        [theme: themeString]: overrideObject | string
      }
    
  }
}

topicTag: {
    borderColor: {
      $value: '{base.color.transparent}',
      $type: 'color',
      $extensions: {
        'org.primer.overrides': 
          {
          "light": {
              $value: '{base.color.neutral.10}',
            },
            dark: '{base.color.neutral.7}',
          },
      },
    },
  },

When building the tokens we need to provide a theme to the PlatformConfig options property, e.g.:

css: css(`css/${filename}.css`, options.prefix, options.buildPath, {
        themed: options.themed,
        themeOverrides: {
          theme: options.theme
        },
      }),

If a value with this theme is defined on the token, it will be used, otherwise the "default" $value will be used.

The benefit of using a pre-processor to other solutions is, that the token can still be transformed normally in the transformation flow. No custom code is required, contributors don't need to understand preprocessors or how this works, to add contributions to other parts.

List of notable changes: